home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Mac Game Programming Gurus / TricksOfTheMacGameProgrammingGurus.iso / More Source / C⁄C++ / picture / unix stuff / picthelp.txt < prev   
Text File  |  1993-09-23  |  10KB  |  224 lines
  1. Help file for the Picture project.
  2.  
  3. Ralph Gonzalez, PO Box 54, Newark, DE 19711, USA.
  4.  
  5.  
  6.  
  7. INTRODUCTION:
  8.  
  9. Picture is a free class library for displaying and animating three-dimensional 
  10. color wire-frame drawings, although it may also be used for displaying two-
  11. dimensional drawings.  It supports (1) segmentation of graphical entities, (2) 
  12. multiple viewpoints and multiple projection windows, and (3) animation with an 
  13. independent frame of reference for each (nested) segment.  It was written with 
  14. the object-oriented Think C 5.0 compiler by Symantec Corp., using Macintosh 
  15. computers.  However, COMPLETE PORTABILITY of Picture-based applications is 
  16. possible to those environments for which a Screen class has been written.  
  17. Presently Screen classes for Macintosh/Think C, PC-compatible (EGA/VGA)/Borland 
  18. Turbo C++, and Unix/X Window/gnu C++ combinations exist.  Few changes should be 
  19. needed to use these classes with different C++ compilers.
  20.  
  21.  
  22. DISTRIBUTION:
  23.  
  24. Picture may be distributed freely as long as this Help file is included.  It is 
  25. intended for educational use only - permission is required for commercial use.  
  26. Users are encouraged to add functionality to the existing Picture library, or to 
  27. write new Screen classes for other computers.  Please send any such additions to 
  28. me, including documentation, so I can include them for distribution.  I would 
  29. also be interested in seeing well-documented copies of any Picture applications 
  30. you come up with.
  31.  
  32. Note that an ealier version of the Picture library was released.  The earlier
  33. version lacked C++ style constructors and destructors, and X Window portability.
  34.  
  35.  
  36. DESCRIPTION:
  37.  
  38. Picture consists of the following major classes:  Camera, Frame, Projector, 
  39. Generic_Screen, Segment, Transformation, and Generic_Pict.  The following 
  40. illustrates the class hierarchy, showing the inheritance relationships:
  41.  
  42. Generic_Class
  43.     Camera
  44.     Coord2
  45.     Coord3
  46.     Error
  47.     Frame
  48.     Generic_Pict
  49.         An_Ring_Pict
  50.         Dy_Cube_Pict
  51.         Ring_Pict
  52.         Simple_Pict
  53.     Generic_Screen
  54.         Mac_Screen
  55.         PC_Screen
  56.         X_Screen
  57.     Projector
  58.         Backdrop_Projector
  59.         Corner_Projector
  60.     Segment
  61.         Fast_Cube
  62.         Lline
  63.         Nested_Segment
  64.             Animated_Segment
  65.                 Animated_Ring
  66.                 Atomic_Ring
  67.                 Dynamic_Segment
  68.                     Dynamic_Cube
  69.                     Fast_Dynamic_Cube
  70.             Cube
  71.             Ring
  72.     Transformation
  73.         Rotation_X
  74.         Rotation_Y
  75.         Rotation_Z
  76.         Scaling
  77.         Translation
  78.         World_To_Camera
  79.  
  80.  
  81. Three-dimensional figures are defined by creating new classes which are 
  82. descendants of the Segment class.  An existing descendant of Segment is 
  83. Nested_Segment.  Figures which are defined as descendants of Nested_Segments can 
  84. easily be composed of combinations of existing figures.  (See the description of 
  85. the file segment.h, below.)  An existing descendant of Nested_Segment is 
  86. Animated_Segment.  Figures which derive from this class can define animate() 
  87. methods which indicate how the nested segments are to be animated.  
  88. Dynamic_Segment's are Animated_Segment's which maintain velocity and 
  89. acceleration vectors for physics simulations.
  90.  
  91. Segments can be moved and animated using Transformations, including scaling, 
  92. translation, and rotation about the coordinate axes.
  93.  
  94. Camera objects are positioned and oriented in three dimensions to serve as 
  95. viewpoints.  (See the description of the file camera.h, below.)  A rectangular 
  96. cropping region (or Frame) on the Camera's projection plane declares the size of 
  97. the "photo" for use with a Projector, as mentioned below.
  98.  
  99. Each application should contain a single "screen" object (whose class is a 
  100. descendant of Generic_Screen) which is appropriate for the environment (although 
  101. it may be possible to allow multiple screen objects, for situations where 
  102. multiple monitors are available).  Presently there exist Mac_Screen, PC_Screen, 
  103. and X_Screen classes, and it is hoped that more will become available in the 
  104. future.
  105.  
  106. The application may contain several Projector objects, each of which is 
  107. associated with a rectangular window (or Frame) on the Screen.  (It is also 
  108. possible to have a console window for text I/O, as mentioned in the description 
  109. of the file pict.c, below.)  The application may also contain several Camera 
  110. objects and Segments.  Segments are drawn by specifying which Camera and which 
  111. Projector to use.  Segments may be drawn repeatedly in a loop to obtain 
  112. animation.
  113.  
  114. A class called Generic_Pict serves as a generic Picture application, which 
  115. defines Screen, Error, and Backdrop_Projector (black backdrop) objects.  The 
  116. easiest way to create a new Picture application is to define a new class which 
  117. inherits these properties from Generic_Pict and overrides the run() method (and 
  118. defines a new constructor and destructor) to draw specialized figures.  These 
  119. specialized figures should be defined elsewhere as subclasses of Segment.  Four 
  120. sample descendants of Generic_Pict are included, and mentioned below.
  121.  
  122. Note that the Error object automatically reports errors to the file error.fil.  
  123. Examine this file after running the application to aid debugging.
  124.  
  125.  
  126. FILES:
  127.  
  128. picthelp.txt   this file.
  129. Pict Help (MacWrite)   same as this file, but with text formatting and graphics.
  130. picture.pi     sample Think C project file.
  131. Makefile       sample Unix Makefile.  You may need to change the ".c" extension
  132.                to ".cc" for all the source files.
  133.  
  134. (The following files comprise the Picture library.  Please read the comments in 
  135. the source and header files of any classes you will override, especially 
  136. Generic_Pict.)
  137.  
  138. class.h         defines Generic_Class, from which all classes derive.
  139. class.c         methods for Generic_Class, enables reporting when a constructor
  140.                 fails, though this isn't used in the Picture code.
  141. error.h         defines Error class, for reporting certain errors to error.fil.
  142. error.c         Error methods.
  143. screen.h        defines Generic_Screen class encapsulating low-level graphics
  144.                 instructions.
  145. screen.c        methods for Generic_Screen.
  146. macscrn.h       Mac_Screen for Macintosh/Think C environment.
  147. macscrn.c       methods for Mac_Screen.
  148. pcscrn.h        PC_Screen for PC/Borland Turbo C++.
  149. pcscrn.c        methods for PC_Screen.
  150. xscrn.h         X_Screen for Unix/X Window/gnu C++.
  151. xscrn.c         methods for X_Screen.
  152. color.h         defines mapping of color values, for color or B&W displays.
  153. camera.h        defines Camera class representing the viewpoint for 3D
  154.                 perspective projection.  Describes coordinate system used.
  155. camera.c        Camera methods.
  156. project.h       defines Projector class representing the mapping from the
  157.                 Camera's projection plane to a screen window
  158. project.c       Projector methods
  159. backdrop.h      defines Backdrop_Projector, which simply fills the entire screen
  160.                 with a single color to hide the operating system desktop.
  161. backdrop.c      Backdrop_Projector methods.
  162. coord.h         defines Coord2 and Coord3 classes for 2D and 3D coordinates.
  163. coord.c         defines operations on Coord2 and Coord3 objects.
  164. trans.h         defines Transformation class and descendants: Translation,
  165.                 Scaling, Rotation_X, Rotation_Y, and Rotation_Z.  Also a
  166.                 composite transformation for 3D perspective transformation.
  167. trans.c         methods for these transformation classes.
  168. frame.h         defines the Frame class, for 2D mappings.
  169. frame.c         methods for Frame.
  170. segment.h       defines Segment and Nested_Segment for defining figures.  Each
  171.                 Nested_Segment maintains an instance variable representing the
  172.                 cascaded transformations which have been applied to it.  Thus
  173.                 the segments which are contained within it may be transformed
  174.                 with reference to a local coordinate system, without regard to
  175.                 transformations which are applied to the entire Nested_Segment.
  176. segment.c       Segment methods.
  177. line.h          defines Line class, a simple Segment descendant.
  178. line.c          Line methods.
  179. cube.h          defines Cube, a descendant of Nested_Segment consisting of
  180.                 several Lines.  Also defines Fast_Cube, a direct descendant of
  181.                 Segment which draws faster.
  182. cube.c          Cube methods.
  183. ring.h          defines Ring, a Nested_Segment descendant for ring-shaped
  184.                 collections of Cubes.
  185. ring.c          Ring methods.
  186. animate.h       defines Animated_Segment class, a Nested_Segment descendant for
  187.                 defining animations of nested segments.
  188. animate.c       Animated_Segment methods.
  189. atring.h        defines Atomic_Ring, an Animated_Segment descendant very similar
  190.                 to Ring.
  191. atring.c        Atomic_Ring methods.
  192. anring.h        defines Animated_Ring, an Animated_Segment whose nested segments
  193.                 may also be animated.
  194. anring.c        Animated_Ring methods.
  195. dynamic.h       defines Dynamic_Segment class, an Animated_Segment descendant
  196.                 supporting dynamics.
  197. dynamic.c       Dynamic_Segment methods.
  198. dycube.h        defines Dynamic_Cube and Fast_Dynamic_Cube classes.
  199. dycube.c        Dynamic_Cube and Fast_Dynamic_Cube methods.
  200. pict.h          defines Generic_Pict, a generic class from which the main
  201.                 application class should be derived.
  202. pict.c          Generic_Pict methods.  Also contains comments on how to use
  203.                 a window for stdio-type text input and output.
  204. main.c          main() function allocating a descendant of Generic_Pict.
  205.  
  206. (The following files are used to demonstrate how to use the Picture library.  
  207. Simple_Pict, Ring_Pict, An_Ring_Pict, and Dy_Cube_Pict are sample pictures 
  208. derived from Generic_Pict.  Comments in main.c indicate how to compile the 
  209. applications.)
  210.  
  211. simpict.h       defines Simple_Pict, a sample 2D picture.
  212. simpict.c       Simple_Pict methods.
  213. ringpict.h      defines Ring_Pict, a sample 3D picture.
  214. ringpict.c      Ring_Pict methods.
  215. anringpi.h      defines An_Ring_Pict, a sample animated 3D picture.
  216. anringpi.c      An_Ring_Pict methods.
  217. dycubpic.h      defines Dy_Cube_Pict, a sample dynamic animated 3D picture.
  218. dycubpic.c      Dy_Cube_Pict methods.
  219.  
  220.  
  221. REFERENCES:
  222.  
  223. Hearn & Baker, "Computer Graphics", Prentice-Hall, 1986
  224.